docs: Clarify OUTPUT record vs output object in sync endpoints by jancurn · Pull Request #2689 · apify/apify-docs

jancurn · 2026-06-24T12:15:58Z

Fixes outdated docs that implied an Actor has a single canonical output under the OUTPUT key. Clarifies across the API reference and platform docs that the Actor output object is defined by the output schema and links to results that may live in the dataset, key-value store, or elsewhere.

Slack thread

…utput The synchronous Actor/task run endpoints implied every Actor has a single canonical output stored under the OUTPUT key. Clarify that OUTPUT is only the default key-value store record key (the outputRecordKey default), that Actors aren't required to write it, that results are often in a dataset, and that it's unrelated to the Actor output schema. Also rename the POST run-sync summary to reflect it returns a key-value store record. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

Reword the clarification so the OUTPUT key-value store record is explicitly distinguished from the Actor output object, linking to the output object definition in the output schema docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

Rewrite the Output section to match the actor-whitepaper model: the Actor output object is defined solely by the output schema, returned via API immediately when the run starts, and links to results that may live in the dataset, key-value store, or elsewhere - rather than equating output with the dataset. Also complete the page description to cover output. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

Reword dataset-schema, key-value-store-schema, running, Make, n8n, and academy pages so they stop equating an Actor's output with one storage. Where the text means the dataset items or the produced results, say that explicitly, consistent with the output-object model defined by the output schema. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account · 2026-06-24T12:16:33Z

✅ Preview for this PR (commit f2de4e34) is ready at https://pr-2689.preview.docs.apify.com (see action run).

apify-service-account · 2026-06-24T12:18:32Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#888

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

jancurn · 2026-06-24T12:19:29Z

  summary: Run task synchronously
  description: |
-    Run a specific task and return its output.
+    Runs a specific task and returns its output.


Change this to:

Runs an Actor task and synchronously returns a key-value store record.

Done in d926dd7 — both the GET and POST descriptions now read "Runs an Actor task and synchronously returns a key-value store record."

Generated by Claude Code

jancurn · 2026-06-24T12:21:05Z

@@ -65,6 +74,15 @@ post:
  description: |
    Runs an Actor task and synchronously returns its output.


Change this to:

Runs an Actor task and synchronously returns a key-value store record.

Done in d926dd7 — both the GET and POST descriptions now read "Runs an Actor task and synchronously returns a key-value store record."

Generated by Claude Code

Apply reviewer feedback: the synchronous run endpoints return a key-value store record, not a generic Actor output. Updated the first sentence of all four plain run-sync endpoint descriptions for consistency. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

Reviewer follow-up: make both GET and POST first sentences in the actor-task run-sync endpoint read identically as "Runs an Actor task and synchronously returns a key-value store record." Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account · 2026-06-24T12:24:09Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#889

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

apify-service-account · 2026-06-24T12:25:56Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#890

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

…ject The OUTPUT key-value store record isn't a convention - it's a legacy way of returning results that the Actor output object replaces. Reword the four run-sync descriptions accordingly and fold in the output object link. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account · 2026-06-24T12:30:26Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#891

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

jancurn · 2026-06-24T12:41:15Z

 title: Dataset schema specification
 sidebar_position: 5
-description: Define a dataset schema to control how your Actor output data is structured, validated, and displayed in Apify Console UI and API responses.
+description: Define a dataset schema to control how your Actor's dataset is structured, validated, and displayed in Apify Console, the API, and integrations.


"how your Actor's results"

Done in 617c4bc — the description now reads "...how your Actor's results are structured, validated, and displayed...".

Generated by Claude Code

Reviewer feedback: describe the dataset schema as controlling how the Actor's results are structured, validated, and displayed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

jancurn · 2026-06-24T12:43:46Z

 ## Output

-While the input object provides a way to instruct Actors, an Actor can also generate an output, usually stored in its default [Dataset](../../storage/dataset), but some additional files might be stored in its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn more about its output.
+An Actor can produce results in several places. Structured, tabular results are usually stored in the run's default [Dataset](../../storage/dataset), while files and other unstructured data go to its [Key-value store](../../storage/key-value-store). Always read the Actor's README to learn what an Actor produces and where it stores it. For more details about storages, visit the [Storage](../../storage/index.md) section.


"in the run's default (or additional) Dataset"

Done in e6accf5 — line now reads "...stored in the run's default (or additional) Dataset...".

Generated by Claude Code

Reviewer feedback on the input-and-output Output section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account · 2026-06-24T12:45:15Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#892

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

apify-service-account · 2026-06-24T12:47:29Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#893

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

janbuchar

Thanks for the effort. I have left a couple of comments, please resolve them before merging.

janbuchar · 2026-06-24T12:45:08Z

  description: |
-    Key of the record from run's default key-value store to be returned
-    in the response. By default, it is `OUTPUT`.
+    Key of the record from the run's default key-value store to return in the


This parameter is only used for the run-sync endpoint "family" (currently there are four of those). After this change, I'd argue that this parameter deserves it's own file (runSyncParameters.yaml) to make it super clear that the new description only makes sense for run-sync.

Done in f2de4e3 — moved outputRecordKey into a new runSyncParameters.yaml and updated the four run-sync $refs.

Generated by Claude Code

janbuchar · 2026-06-24T12:54:21Z

+    the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition);
+    Actors aren't required to store a record under this key, so the response may
+    not contain any data. Use the `outputRecordKey` query parameter to return a
+    different record. Many Actors store their results in a dataset instead.


Many Actors store their results in a dataset instead.

Or in multiple datasets. Or the output can be multiple records in the KVS. Or it might produce no output at all.

Maybe we could just remove this sentence.

Done in f2de4e3 — removed the "Many Actors store their results in a dataset instead" sentence from the run-sync descriptions.

Generated by Claude Code

janbuchar · 2026-06-24T12:56:25Z

 ## Writing output {#writing-output}

-Similarly to reading input, you can write the Actor's output either by using the Apify SDK in Node.js or by manually writing a utility function to do so.
+Similarly to reading input, you can write the Actor's results either by using the Apify SDK in Node.js or by manually writing a utility function to do so.


I'd emphasize that results generally go into storages (dataset, KVS, request queues)

Done in f2de4e3 — now notes that an Actor's results generally go into its storages (dataset, key-value store, or request queue).

Generated by Claude Code

janbuchar · 2026-06-24T12:59:15Z

 ## Getting the results from dataset

-Actors usually store their output in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.
+Actors usually store their results in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.


Suggested change

Actors usually store their results in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.

An Actor usually stores its results in a default dataset created separately for each run. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.

Done in f2de4e3 — applied the suggestion.

Generated by Claude Code

- Remove the "Many Actors store their results in a dataset instead" sentence from the run-sync descriptions (results can be in multiple datasets, KVS records, or none). - Move the run-sync-only outputRecordKey parameter into its own runSyncParameters.yaml component file. - Emphasize that an Actor's results generally go into its storages in the deploying-your-code tutorial. - Apply the suggested wording in the PHP tutorial. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account · 2026-06-24T13:08:41Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#894

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

claude added 4 commits June 24, 2026 09:11

jancurn requested review from fnesveda, honzajavorek, janbuchar, marcel-rbro and szaganek as code owners June 24, 2026 12:15

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#888

Closed

jancurn commented Jun 24, 2026

View reviewed changes

claude added 2 commits June 24, 2026 12:21

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#889

Closed

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#890

Closed

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#891

Closed

jancurn commented Jun 24, 2026

View reviewed changes

docs: note results may be in default or additional dataset

e6accf5

Reviewer feedback on the input-and-output Output section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019gsX2hWLtZXSDiqtLphzSc

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#892

Closed

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#893

Closed

jancurn requested review from TC-MO and removed request for fnesveda, honzajavorek and szaganek June 24, 2026 12:48

janbuchar approved these changes Jun 24, 2026

View reviewed changes

apify-service-account mentioned this pull request Jun 24, 2026

[TODO]: update generated models from apify-docs PR #2689 apify/apify-client-python#894

Closed

		@@ -65,6 +74,15 @@ post:
		description: \|
		Runs an Actor task and synchronously returns its output.

	Actors usually store their results in a default dataset. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.
	An Actor usually stores its results in a default dataset created separately for each run. The [Actor runs endpoint](/api/v2/actor-runs) lets you get overall info about an Actor run's default dataset.

Conversation

jancurn commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

jancurn Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

janbuchar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jancurn commented Jun 24, 2026 •

edited

Loading

apify-service-account commented Jun 24, 2026 •

edited

Loading

jancurn Jun 24, 2026 •

edited

Loading